"""
文件路径操作工具集 - 提供跨平台的文件路径处理功能

核心功能：
1. 路径解析与拆分
2. 目录创建与管理
3. 文件复制与写入
4. 路径标准化处理

技术特性：
- 兼容Windows/Unix路径格式
- 异常安全处理
- 支持路径自动展开（~扩展为家目录）
- 线程安全操作
"""

import os
from os import path
from shutil import copyfile
import errno

# 暴露的接口列表
__all__ = ['split', 'make', 'copy_to_dir', 'process', 'write_file']


def split(directory):
    """拆分完整路径为目录、文件名和扩展名

    参数：
        directory (str): 待拆分的完整路径

    返回：
        tuple: (目录路径, 文件名, 扩展名)

    示例：
        >>> split('/home/user/file.txt')
        ('/home/user', 'file', '.txt')
    """
    directory = process(directory)  # 先标准化路径
    name, ext = path.splitext(path.basename(directory))  # 分离文件名与扩展名
    return path.dirname(directory), name, ext  # 返回目录路径、纯文件名、扩展名


def make(directory):
    """递归创建目录（已存在时不报错）

    参数：
        directory (str): 待创建的目录路径

    异常：
        OSError: 非"目录已存在"错误时抛出
    """
    try:
        os.makedirs(directory)  # 递归创建目录
    except OSError as e:
        if e.errno != errno.EEXIST:  # 忽略目录已存在错误
            raise  # 其他错误正常抛出


def copy_to_dir(file, directory):
    """复制文件到指定目录

    参数：
        file (str): 源文件路径
        directory (str): 目标目录路径

    注意：
        保持原文件名，不支持重命名
    """
    file_path = path.join(directory, path.basename(file))  # 拼接目标路径
    copyfile(file, file_path)  # 执行文件复制


def process(directory, create=False):
    """标准化路径处理

    参数：
        directory (str): 待处理路径
        create (bool): 是否自动创建目录

    处理步骤：
        1. 展开家目录(~)
        2. 规范化路径分隔符
        3. 转换为绝对路径
        4. 可选创建目录

    返回：
        str: 标准化后的路径
    """
    directory = path.expanduser(directory)  # 处理~符号
    directory = path.normpath(directory)  # 规范化路径分隔符
    directory = path.abspath(directory)  # 转换为绝对路径
    if create:
        make(directory)  # 按需创建目录
    return directory


def write_file(contents, filename, directory=".", append=False):
    """安全写入文件内容

    参数：
        contents (str): 要写入的内容
        filename (str): 目标文件名
        directory (str): 目标目录（默认当前目录）
        append (bool): 是否为追加模式

    返回：
        str: 写入文件的完整路径

    特点：
        - 自动处理路径标准化
        - 使用with语句确保资源释放
        - 支持追加/覆盖两种模式
    """
    full_name = path.join(process(directory), filename)  # 标准化路径
    mode = "a" if append else "w"  # 模式选择
    with open(full_name, mode) as file_handle:  # 安全上下文管理
        file_handle.write(contents)  # 执行写入
    return full_name